---
created:
  source_filename: /home/runner/work/mknodes/mknodes/mknodes/pages/mkclasspage/__init__.py
  source_function: MkClassPage.__init__
  source_line_no: 46
hide:
- toc
icon: material/api
status: new
template: The nodes/Documentation nodes/mkclidoc.html
title: MkCliDoc
---

[:fa-brands-github: Show source on GitHub](https://github.com/phil65/mknodes/blob/main/mknodes/basenodes/mkclidoc/__init__.py)

### Node for showing documentation for click / typer CLI apps.


=== "Examples"
    ### Example: **MkDocs-MkNodes CLI**
    !!! jinja "Jinja"
        ``` {.jinja }
        {{ "mkdocs_mknodes.cli:cli" | MkCliDoc }}

        ```

    !!! python "Python"
        ``` {.python }
        MkCliDoc('mkdocs_mknodes.cli:cli')
        ```

    ===! "Rendered"
        ## MkNodes

        🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀

        Check out https://phil65.github.io/mkdocs-mknodes/ !

        ```` {.python }
        mknodes [OPTIONS] COMMAND [ARGS]...
        ````

        ### `--install-completion`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Install completion for the current shell.


        ### `--show-completion`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show completion for the current shell, to copy it or customize the installation.


        ### `--help`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.

    === "Markdown"
        ``` {.markdown }
        ## MkNodes

        🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀

        Check out https://phil65.github.io/mkdocs-mknodes/ !

        ```` {.python }
        mknodes [OPTIONS] COMMAND [ARGS]...
        ````

        ### `--install-completion`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Install completion for the current shell.


        ### `--show-completion`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show completion for the current shell, to copy it or customize the installation.


        ### `--help`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.




        ```

    === "Html"
        ``` {.html }
        <h2 id="mknodes">MkNodes</h2>
        <p>🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀</p>
        <p>Check out <a href="https://phil65.github.io/mkdocs-mknodes/">https://phil65.github.io/mkdocs-mknodes/</a> !</p>
        <div class="highlight"><pre><span></span><code><span class="n">mknodes</span> <span class="p">[</span><span class="n">OPTIONS</span><span class="p">]</span> <span class="n">COMMAND</span> <span class="p">[</span><span class="n">ARGS</span><span class="p">]</span><span class="o">...</span>
        </code></pre></div>
        <h3 id="-install-completion"><code>--install-completion</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Install completion for the current shell.</p>
        <h3 id="-show-completion"><code>--show-completion</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show completion for the current shell, to copy it or customize the installation.</p>
        <h3 id="-help"><code>--help</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.</p>
        ```

    === "Repr tree"
        ```
        MkCliDoc
        ╰── MkHeader('`--help`', level=3)
        ╰── MkMaterialBadge('mdi:flag', 'Flag')
        ```

    ### Example: **SubCommand**
    !!! jinja "Jinja"
        ``` {.jinja }
        {{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }}

        ```

    !!! python "Python"
        ``` {.python }
        MkCliDoc('mkdocs_mknodes.cli:cli', prog_name='build')
        ```

    ===! "Rendered"
        ## build

        Create a MkNodes-based website, locally or remotely.

        Runs the build script on given repository (either locally or a hosted one), adapts
        the config file automatically and creates the HTML website in given site dir.

        Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/

        ```` {.python }
        mknodes build [OPTIONS]
        ````

        ### `--repo-url`, `-r`

        Repository URL of the target package. Can be remote or local.


        ### `--build-fn`, `-b`

        Path to the build script. (form: `path.to.module:function` )


        ### `--site-dir`, `-d`

        **Default:** site
        Path to the folder where the HTML should get written.


        ### `--clone-depth`, `-c`

        Git clone depth in case repository is remote. Important for changelog generation.


        ### `--config-path`, `-p`

        **Default:** mkdocs.yml
        Path to the config file.


        ### `--theme`, `-t`

        **Default:** material
        Theme to use for the build. Overrides config setting.


        ### `--strict`, `-s`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Strict mode (fails on warnings)


        ### `-u`, `--use-directory-urls`

        **Default:** True
        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Use directory-style URLs.


        ### `--verbose`, `-v`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Enable verbose output. (`DEBUG` level)


        ### `--quiet`, `-q`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Suppress output during build.


        ### `--help`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.

    === "Markdown"
        ``` {.markdown }
        ## build

        Create a MkNodes-based website, locally or remotely.

        Runs the build script on given repository (either locally or a hosted one), adapts
        the config file automatically and creates the HTML website in given site dir.

        Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/

        ```` {.python }
        mknodes build [OPTIONS]
        ````

        ### `--repo-url`, `-r`

        Repository URL of the target package. Can be remote or local.


        ### `--build-fn`, `-b`

        Path to the build script. (form: `path.to.module:function` )


        ### `--site-dir`, `-d`

        **Default:** site
        Path to the folder where the HTML should get written.


        ### `--clone-depth`, `-c`

        Git clone depth in case repository is remote. Important for changelog generation.


        ### `--config-path`, `-p`

        **Default:** mkdocs.yml
        Path to the config file.


        ### `--theme`, `-t`

        **Default:** material
        Theme to use for the build. Overrides config setting.


        ### `--strict`, `-s`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Strict mode (fails on warnings)


        ### `-u`, `--use-directory-urls`

        **Default:** True
        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Use directory-style URLs.


        ### `--verbose`, `-v`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Enable verbose output. (`DEBUG` level)


        ### `--quiet`, `-q`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Suppress output during build.


        ### `--help`

        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon">:mdi-flag:</span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.




        ```

    === "Html"
        ``` {.html }
        <h2 id="build">build</h2>
        <p>Create a MkNodes-based website, locally or remotely.</p>
        <p>Runs the build script on given repository (either locally or a hosted one), adapts
        the config file automatically and creates the HTML website in given site dir.</p>
        <p>Further info here: <a href="https://phil65.github.io/mkdocs-mknodes/CLI/">https://phil65.github.io/mkdocs-mknodes/CLI/</a></p>
        <div class="highlight"><pre><span></span><code><span class="n">mknodes</span> <span class="n">build</span> <span class="p">[</span><span class="n">OPTIONS</span><span class="p">]</span>
        </code></pre></div>
        <h3 id="-repo-url-r"><code>--repo-url</code>, <code>-r</code></h3>
        <p>Repository URL of the target package. Can be remote or local.</p>
        <h3 id="-build-fn-b"><code>--build-fn</code>, <code>-b</code></h3>
        <p>Path to the build script. (form: <code>path.to.module:function</code> )</p>
        <h3 id="-site-dir-d"><code>--site-dir</code>, <code>-d</code></h3>
        <p><strong>Default:</strong> site
        Path to the folder where the HTML should get written.</p>
        <h3 id="-clone-depth-c"><code>--clone-depth</code>, <code>-c</code></h3>
        <p>Git clone depth in case repository is remote. Important for changelog generation.</p>
        <h3 id="-config-path-p"><code>--config-path</code>, <code>-p</code></h3>
        <p><strong>Default:</strong> mkdocs.yml
        Path to the config file.</p>
        <h3 id="-theme-t"><code>--theme</code>, <code>-t</code></h3>
        <p><strong>Default:</strong> material
        Theme to use for the build. Overrides config setting.</p>
        <h3 id="-strict-s"><code>--strict</code>, <code>-s</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Strict mode (fails on warnings)</p>
        <h3 id="-u-use-directory-urls"><code>-u</code>, <code>--use-directory-urls</code></h3>
        <p><strong>Default:</strong> True
        <span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Use directory-style URLs.</p>
        <h3 id="-verbose-v"><code>--verbose</code>, <code>-v</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Enable verbose output. (<code>DEBUG</code> level)</p>
        <h3 id="-quiet-q"><code>--quiet</code>, <code>-q</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Suppress output during build.</p>
        <h3 id="-help"><code>--help</code></h3>
        <p><span class="md-typeset mdx-badge">
          <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
          <span class="mdx-badge__text">Flag</span>
        </span>
        Show this message and exit.</p>
        ```

    === "Repr tree"
        ```
        MkCliDoc
        ╰── MkHeader('`--help`', level=3)
        ╰── MkMaterialBadge('mdi:flag', 'Flag')
        ```


=== "DocStrings"
    ::: mknodes.MkCliDoc
        options:
          show_docstring_description: False



=== "Base classes"
    | Name | Children | Inherits |
    |--- | --- | --- |
    | **<font size='4'>[MkTemplate](https://phil65.github.io/mknodes/)</font>**<br>*<font size='1'>mknodes.templatenodes.mktemplate</font>*<br>Node representing a jinja template\. | <ul><li>[MkCliDoc](https://phil65.github.io/mknodes/)</li><li>[MkMaterialBadge](https://phil65.github.io/mknodes/)</li><li>[MkImageCompare](https://phil65.github.io/mknodes/)</li><li>[MkImageSlideshow](https://phil65.github.io/mknodes/)</li><li>[MkIFrame](https://phil65.github.io/mknodes/)</li><li>[MkCard](https://phil65.github.io/mknodes/)</li><li>[MkInstallGuide](https://phil65.github.io/mknodes/)</li><li>[MkCodeOfConduct](https://phil65.github.io/mknodes/)</li><li>[MkCommitConventions](https://phil65.github.io/mknodes/)</li><li>[MkPullRequestGuidelines](https://phil65.github.io/mknodes/)</li><li>[MkDevEnvSetup](https://phil65.github.io/mknodes/)</li><li>...</li></ul> | <ul><li>[MkContainer](https://phil65.github.io/mknodes/)</li></ul> |

=== "⋔ Inheritance diagram"
    ``` mermaid
    graph TD
      94721308870576["mkclidoc.MkCliDoc"]
      94721308869584["mktemplate.MkTemplate"]
      94721311697232["mkcontainer.MkContainer"]
      94721308848336["mknode.MkNode"]
      94721311766592["node.Node"]
      140564252373184["builtins.object"]
      94721308869584 --> 94721308870576
      94721311697232 --> 94721308869584
      94721308848336 --> 94721311697232
      94721311766592 --> 94721308848336
      140564252373184 --> 94721311766592
    ```
=== "NodeFile"
    ``` {.toml  title='/home/runner/work/mknodes/mknodes/mknodes/basenodes/mkclidoc/metadata.toml'}
    [metadata]
    icon = "mdi:api"
    name = "MkCliDoc"

    [examples.cli]
    title = "MkDocs-MkNodes CLI"
    jinja = """
    {{ "mkdocs_mknodes.cli:cli" | MkCliDoc }}
    """

    [examples.sub_command]
    title = "SubCommand"
    jinja = """
    {{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }}
    """

    [examples.argparse]
    title = "ArgumentParser"
    python = """
    from git_changelog import cli
    import mknodes as mk

    parser = cli.get_parser()
    mk.MkCliDoc(parser)
    """

    [fragments]
    param_template = """
    {{ param.opt_str | MkHeader(level=3) }}

    {% if param.required %}
    "{{ "REQUIRED" | md_style(bold=True) }}"
    {% endif %}
    {% if param.envvar %}
    Environment variable{{ param.envvar }}
    {% endif %}
    {% if param.multiple %}
    {{ "Multiple values allowed." | md_style(bold=True) }}
    {% endif %}
    {% if param.default %}
    {{ "Default:" | md_style(bold=True) }} {{ param.default }}
    {% endif %}
    {% if param.is_flag %}
    {{ "mdi:flag" | MkMaterialBadge("Flag") }}
    {% endif %}
    {% if param.help %}
    {{ param.help }}
    {% endif %}
    """
    command_template = """
    {{ info.name | MkHeader }}

    {{ info.description }}

    {{ info.usage | MkCode }}

    {% for param in info.params %}
    {{ "fragments/param_template" | render_template(param=param) }}

    {% endfor %}

    """

    [output.markdown]
    template = """
    {% if node.info %}
    {{ "fragments/command_template" | render_template(info=node.info) }}
    {% if node.show_subcommands %}
    {% for sub_info in node.info.subcommands.values() %}
    {{ "fragments/command_template" | render_template(info=sub_info) }}
    {% endfor %}
    {% endif %}
    {% endif %}
    """

    ```
=== "Code"
    ``` {.python  title='mknodes.basenodes.mkclidoc.MkCliDoc' linenums='16'}
    class MkCliDoc(mktemplate.MkTemplate):
        """Node for showing documentation for click / typer CLI apps."""

        ICON = "material/api"

        def __init__(
            self,
            target: str | argparse.ArgumentParser | None = None,
            *,
            prog_name: str | None = None,
            show_hidden: bool = False,
            show_subcommands: bool = False,
            **kwargs: Any,
        ):
            r"""Constructor.

            Args:
                target: Dotted path to click group / typer instance / ArgumentParser
                prog_name: Program name
                show_hidden: Show commands and options that are marked as hidden.
                show_subcommands: List subcommands of a given command.
                kwargs: Keyword arguments passed to parent
            """
            super().__init__("output/markdown/template", **kwargs)
            self.target = target
            self.prog_name = prog_name
            self.show_hidden = show_hidden
            self.show_subcommands = show_subcommands

        @property
        def info(self) -> clinspector.CommandInfo | None:
            import importlib

            match self.target:
                case str():
                    module, command = self.target.split(":")
                    prog_name = self.prog_name
                    mod = importlib.import_module(module)
                    instance = getattr(mod, command)
                case None:
                    if cli_eps := self.ctx.metadata.entry_points.get_group("console_scripts"):
                        module, command = cli_eps[0].value.split(":")
                        prog_name = cli_eps[0].name
                        mod = importlib.import_module(module)
                        instance = getattr(mod, command)
                    else:
                        return None
                case _:
                    instance = self.target
                    prog_name = self.prog_name
            return clinspector.get_cmd_info(instance, command=prog_name)

    ```